xtf-linkui

Appearance

安卓 ios 鸿蒙 后台下载，后台下载任务，后台下载插件 ​

插件 ID: 28236
来源: https://ext.dcloud.net.cn/plugin?id=28236
适用于 uni-app 和 uni-app x 的 App 端后台下载插件，支持 Android、iOS、Harmony 的任务创建、进度监听、暂停恢复、取消和任务查询。

更新记录 ​

​

                                                    1.0.3（2026-06-07）

优化

​

                                                    1.0.2（2026-06-06）

优化

​

                                                    1.0.1（2026-06-05）

优化存在的问题 查看更多

平台兼容性 ​

uni-app(4.23) ​

| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 | | | √ | √ |

  • |
  • | √ |
  • | 5.0 | √ | 5.0 | | | 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 | | |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • | |

uni-app x(4.25) ​

| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 | | |

  • |
  • | 5.0 | √ | 5.0 |
  • | |

其他 ​

| 多语言 | 暗黑模式 | 宽屏模式 | | | √ | √ | √ | |

xtf-downloadtask ​

xtf-downloadtask 是一个 App 端后台下载插件，适用于 uni-app 和 uni-app x。插件统一提供下载任务的创建、暂停、恢复、取消、查询，以及进度/状态回调能力，适合需要稳定后台下载和任务管理的业务场景。

平台支持 ​

| 平台 | 支持情况 | 说明 | | | Android | 支持 | 原生后台下载实现 | | | iOS | 支持 | 系统后台下载实现 | | | Harmony | 支持 | 原生后台下载实现 | | | Web | 不支持 |

  • | | | 小程序 | 不支持 |
  • | |

适用场景 ​

  • 大文件下载
  • 应用切后台后继续下载
  • 需要任务暂停与恢复
  • 需要在页面中展示下载进度和任务状态

导出内容 ​

  • BackgroundDownloader
  • BackgroundDownloadRequest
  • BackgroundDownloadTask
  • BackgroundDownloadList

快速开始 ​

uni-app x ​

import { BackgroundDownloader } from '@/uni_modules/xtf-downloadtask'
const downloader = new BackgroundDownloader()

uni-app ​

import { BackgroundDownloader } from '@/uni_modules/xtf-downloadtask'
const downloader = new BackgroundDownloader()

启动一个下载任务 ​

const task = downloader.start({
    taskId: `task-${Date.now()}`,
    url: 'https://speed.cloudflare.com/__down?bytes=1048576',
    fileName: 'demo.bin',
    directory: 'downloads/background-demo',
    headers: null,
    showNotification: false
})

Demo 页面 ​

当前示例工程已经提供完整联调页面：

  • pages/demo/background-download.uvue 首页入口：
  • pages/index/index.uvue 这个 Demo 演示了：
  • 创建下载任务
  • 监听下载进度
  • 监听状态变化
  • 暂停当前任务
  • 恢复当前任务
  • 取消当前任务
  • 查询全部任务
  • Android 通知栏默认开关联调
  • Android 通知权限状态检测、权限申请、系统设置跳转
  • Harmony 通知显示开关联调
  • iOS 完成/失败结果通知开关联调

Demo 联调说明 ​

pages/demo/background-download.uvue 中已经把三端通知相关能力拆成可直接点击验证的按钮。

  • Android：可切换默认通知栏开关，对应 setAndroidNotificationEnabled() / getAndroidNotificationEnabled()
  • Android：可刷新通知权限状态、申请 POST_NOTIFICATIONS、跳转系统权限设置页
  • Harmony：可切换默认通知显示开关，对应 setHarmonyNotificationEnabled() / getHarmonyNotificationEnabled()
  • Harmony：可主动请求一次通知授权，对应 requestHarmonyNotificationPermission()；可读取当前通知权限状态，对应 isHarmonyNotificationPermissionEnabled()
  • iOS：可切换完成/失败结果通知开关，对应 setIOSResultNotificationEnabled() / getIOSResultNotificationEnabled() 注意：
  • Android / Harmony 的 showNotification 用于控制下载任务是否显示通知栏或后台提示
  • iOS 不显示 Android 式常驻通知栏，setIOSResultNotificationEnabled() 只控制下载完成或失败时的本地通知
  • Demo 中点击“开始下载”时，Android 与 Harmony 会自动带上当前平台对应的 showNotification 值
  • Android 运行时通知权限依赖 targetSdkVersion >= 33。本项目已在 manifest.json 中配置 35，但调试基座或历史��装包如果未更新到对应目标版本，点击申请时仍可能不会弹系统框，此时请直接使用“打开系统权限设置”验证
  • Harmony 当前会优先调用系统通知授权申请能力；通常首次申请时系统可能弹框，若用户已经同意或拒绝，后续往往不会重复弹框，此时只能引导用户去系统设置确认

核心类型 ​

BackgroundDownloadRequest ​

发起下载时传入的请求对象。 | 字段 | 类型 | 作用 | | | taskId | string | 任务唯一标识。建议由业务层自行生成，避免重复任务互相覆盖。 | | | url | string | 下载地址。建议使用可直接访问的 HTTP/HTTPS 文件直链。 | | | fileName | string | 保存后的文件名。建议带后缀。 | | | directory | string \| null | 保存目录。传 null 时使用插件默认目录逻辑。 | | | headers | UTSJSONObject \| null | 自定义请求头。无额外请求头时传 null。 | | | showNotification | boolean \| null | 单次任务通知开关。传 null 时走平台默认设置。Android/Harmony 表示是否显示通知栏；iOS 当前忽略此字段。 | |

BackgroundDownloadTask ​

下载任务对象，用于页面展示和业务状态判断。 | 字段 | 类型 | 作用 | | | taskId | string | 任务 ID | | | url | string | 原始下载地址 | | | fileName | string | 文件名 | | | directory | string \| null | 保存目录 | | | status | BackgroundDownloadTaskState | 当前任务状态 | | | progress | number | 下载进度，范围通常为 0 到 1 | | | totalBytesWritten | number | 已下载字节数 | | | totalBytesExpected | number | 预期总字节数 | | | localPath | string \| null | 下载完成后的本地路径，未完成时可能为空 | | | errorMessage | string \| null | 失败或异常时的错误信息 | | | nativeTaskId | number | 原生层任务 ID，用于调试或排查问题 | | | updatedAt | number | 最后更新时间戳 | |

BackgroundDownloadTaskState ​

任务状态枚举：

  • idle：初始状态
  • queued：已入队，等待执行
  • running：下载中
  • pausing：正在暂停
  • paused：已暂停
  • pause_failed：暂停失败
  • completed：下载完成
  • failed：下载失败
  • canceled：任务已取消

API 详细说明 ​

new BackgroundDownloader() ​

创建下载器实例。 作用：

  • 初始化插件内部下载环境
  • 建立和原生下载实现的桥接
  • 为当前页面或模块准备任务操作入口 使用建议：
  • 一个页面内通常保留一个实例即可
  • 如果页面需要监听回调，建议在页面生命周期内创建并复用同一个实例 示例：
const downloader = new BackgroundDownloader()

start(request) ​

启动一个后台下载任务。 签名：

start(request: BackgroundDownloadRequest): BackgroundDownloadTask | null

作用：

  • 按传入参数创建下载任务
  • 将任务交给对应平台的原生后台下载通道处理
  • 立即返回当前任务快照，供页面展示 返回值：
  • 成功时返回 BackgroundDownloadTask
  • 启动失败或参数不合法时返��� null 适用时机：
  • 用户点击“开始下载”按钮时
  • 页面恢复后需要重建某个下载任务时 示例：
const task = downloader.start({
    taskId: 'file-001',
    url: 'https://speed.cloudflare.com/__down?bytes=1048576',
    fileName: 'file-001.bin',
    directory: 'downloads/demo',
    headers: null,
    showNotification: false
})

通知相关配置 ​

setAndroidNotificationEnabled(enabled) ​

设置 Android 端默认是否显示通知栏。 签名：

setAndroidNotificationEnabled(enabled: boolean): void

说明：

  • 默认值为 false
  • 仅当单次 start() 未显式传 showNotification 时生效
  • 适合在页面初始化时统一配置 Android 下载任务是否默认显示通知栏

getAndroidNotificationEnabled() ​

读取 Android 端默认通知栏开关。 签名：

getAndroidNotificationEnabled(): boolean

作用：

  • 读取当前 Android 端默认通知栏开关状态
  • 适合在页面加载时回填开关 UI

setHarmonyNotificationEnabled(enabled) ​

设置 Harmony 端默认是否显示通知栏/后台运行提示。 签名：

setHarmonyNotificationEnabled(enabled: boolean): void

说明：

  • 默认值为 false
  • 仅当单次 start() 未显式传 showNotification 时生效
  • 用于控制 Harmony 端后台下载是否默认显示通知栏或后台运行提示

getHarmonyNotificationEnabled() ​

读取 Harmony 端默认通知栏开关。 签名：

getHarmonyNotificationEnabled(): boolean

作用：

  • 读取当前 Harmony 端默认通知显示开关状态
  • 适合在页面加载时回填开关 UI

setIOSResultNotificationEnabled(enabled) ​

设置 iOS 端完成/失败本地通知开关。 签名：

setIOSResultNotificationEnabled(enabled: boolean): void

说明：

  • 默认值为 false
  • 仅在下载完成或下载失败时发送本地通知
  • 不会对进度、暂停、取消发送通知
  • 适合在业务侧给用户一个“下载完成提醒我”的显式开关

getIOSResultNotificationEnabled() ​

读取 iOS 端完成/失败本地通知开关。 签名：

getIOSResultNotificationEnabled(): boolean

作用：

  • 读取当前 iOS 结果通知开关状态
  • 适合在页面加载时回填开关 UI 签名：
getIOSResultNotificationEnabled(): boolean

pause(taskId) ​

暂停指定任务。 签名：

pause(taskId: string): boolean

作用：

  • 请求原生层暂停对应任务
  • 保留当前已下载进度，便于后续恢复 返回值：
  • true：已成功发起暂停请求
  • false：任务不存在，或当前状态不允许暂停 适用时机：
  • 用户手动暂停下载
  • 弱网环境下临时停止下载

resume(taskId) ​

恢复已暂停任务。 签名：

resume(taskId: string): BackgroundDownloadTask | null

作用：

  • 继续下载已暂停的任务
  • 如果服务端支持 Range，通常会从断点继续下载 返回值：
  • 成功时返回最新任务对象
  • 恢复失败时返回 null 适用时机：
  • 用户点击“继续下载”
  • 网络恢复后重启任务

cancel(taskId) ​

取消指定任务。 签名：

cancel(taskId: string): boolean

作用：

  • 终止下载任务
  • 该任务后续不再继续执行 返回值：
  • true：已成功发起取消请求
  • false：任务不存在，或取消失败 适用时机：
  • 用户明确放弃下载
  • 当前任务参数失效，需要重新创建任务

getTask(taskId) ​

查询单个任务。 签名：

getTask(taskId: string): BackgroundDownloadTask | null

作用：

  • 获取某个任务的最新快照
  • 用于页面恢复时还原任务状态 返回值：
  • 查到任务时返回任务对象
  • 未查到时返回 null 适用时机：
  • 页面重新进入时恢复任务信息
  • 业务层主动轮询单个任务状态

getAllTasks() ​

查询全部任务。 签名：

getAllTasks(): BackgroundDownloadList

作用：

  • 返回当前插件维护的全部下载任务
  • 用于渲染任务列表、调试状态、恢复历史任务 返回值：
  • BackgroundDownloadList，本质是任务数组 适用时机：
  • 页面初始化时刷新列表
  • 收到进度/状态回调后重刷任务面板

onProgress(callback) ​

监听任务进度回调。 签名：

onProgress(callback: (task: BackgroundDownloadTask) => void): void

作用：

  • 在下载进度变化时回调最新任务对象
  • 可直接用于更新 UI 进度条、百分比文本、速率估算 回调参数：
  • task：当前进度对应的任务对象 适用时机：
  • 页面需要实时展示下载进度时
  • 业务层需要记录下载过程时 示例：
downloader.onProgress((task) => {
    console.log('progress', task.taskId, task.progress)
})

onStateChange(callback) ​

监听任务状态变化回调。 签名：

onStateChange(callback: (task: BackgroundDownloadTask) => void): void

作用：

  • 在任务状态发生变化时回调
  • 可用于刷新状态标签、提示用户失败原因、切换操作按钮 回调常见场景：
  • queued -> running
  • running -> paused
  • running -> completed
  • running -> failed 示例：
downloader.onStateChange((task) => {
    console.log('state', task.taskId, task.status)
})

clearCallbacks() ​

清理已注册的进度与状态回调。 签名：

clearCallbacks(): void

作用：

  • 解除当前页面对原生回调的监听
  • 避免页面销毁后仍继续更新已失效页面 适用时机：
  • 页面 onUnmounted / onUnload 时
  • 当前页面切换监听对象时 示例：
downloader.clearCallbacks()

推荐调用顺序 ​

典型页面调用流程：

  • 创建 BackgroundDownloader 实例
  • 注册 onProgress 和 onStateChange
  • 调用 getAllTasks() 恢复页面已有任务
  • 用户触发 start() 创建新任务
  • 根据任务 ID 调用 pause() / resume() / cancel()
  • 页面销毁时调用 clearCallbacks()

uni-app x 页面示例 ​

import {
    BackgroundDownloadTask,
    BackgroundDownloader
} from '@/uni_modules/xtf-downloadtask'
const downloader = new BackgroundDownloader()
downloader.onProgress(function(task: BackgroundDownloadTask) {
    console.log(task.progress)
})
downloader.onStateChange(function(task: BackgroundDownloadTask) {
    console.log(task.status)
})

uni-app 页面示例 ​

import { BackgroundDownloader } from '@/uni_modules/xtf-downloadtask'
const downloader = new BackgroundDownloader()
const task = downloader.start({
    taskId: `task-${Date.now()}`,
    url: 'https://speed.cloudflare.com/__down?bytes=1048576',
    fileName: 'demo.bin',
    directory: 'downloads/background-demo',
    headers: null,
    showNotification: false,
})
console.log(task)

平台特别说明 ​

Android ​

  • 走原生后台下载链路
  • 默认不显示通知栏
  • 可通过 setAndroidNotificationEnabled(true) 设置 Android 默认显示通知栏
  • 也可在单次 start() 时传 showNotification: true 覆盖默认值
  • 如需验证完整原生能力，建议使用自定义基座
  • 建议服务端支持 Range，恢复下载更稳定

iOS ​

  • 走系统后台下载能力
  • 不支持 Android 那种常驻通知栏进度
  • 可通过 setIOSResultNotificationEnabled(true) 开启下载完成/失败本地通知
  • 建议使用稳定文件地址，不要依赖临时跳转链接

Harmony ​

Harmony 项目除安装插件外，还需要在项目根目录维护：

harmony-configs/entry/src/main/module.json5

至少需要确保 EntryAbility 具备后台传输能力与权限声明：

{
    "module": {
        "abilities": [
            {
                "name": "EntryAbility",
                "backgroundModes": ["dataTransfer"]
            }
        ],
        "requestPermissions": [
            {
                "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
                "reason": "$string:EntryAbility_label",
                "usedScene": {
                    "when": "always"
                }
            }
        ]
    }
}

插件内部已经处理：

  • showNotification=true 时启动后台运行显示逻辑
  • 可通过 setHarmonyNotificationEnabled(true) 设置 Harmony 默认显示通知栏 但如果入口 EntryAbility 没有配置 backgroundModes，startBackgroundRunning 仍然可能失败。

使用建议 ​

  • taskId 请由业务层保证唯一
  • 页面展示进度时建议使用 progress * 100 转成百分比
  • 如果需要恢复历史任务，页面初始化时先调用 getAllTasks()
  • 如果业务要支持继续下载，服务端最好提供 Content-Length 和 Range
  • 页面销毁前记得 clearCallbacks()，避免无效页面继续收到回调

常见问题 ​

1. 为什么任务能创建，但页面没有进度更新？ ​

通常是因为没有注册 onProgress，或者页面离开后没有重新绑定回调。

2. 为什么恢复下载失败？ ​

常见原因：

  • 任务 ID 不存在
  • 任务并不处于可恢复状态
  • 服务端不支持断点续传

3. 为什么 Harmony 会启动后台任务失败？ ​

优先检查：

  • harmony-configs/entry/src/main/module.json5 是否配置了 backgroundModes
  • 是否声明了 ohos.permission.KEEP_BACKGROUND_RUNNING
  • 用户是否拒绝了后台持续运行权限

4. 为什么 Android 真机联调和标准基座表现不一致？ ​

因为插件依赖原生配置，标准基座下原生依赖能力可能不完全生效，建议使用自定义基座验证。

MIT Licensed

Copyright © 2026 xtf-linkui